APPENDIX A DESCRIPTION FILES A description file is an ASCII file containing information that the Maintenance utility commands CREATE, INDEX, and SINDEX need to perform their operations. Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space). Each element in the description file corresponds to a particular characteristic of a Btrieve file or key definition. The sections in this appendix discuss the following topics: o Rules for Description Files o Description File Example o Description File Elements Rules for Description Files Use the following rules when creating a description file. o Enter elements in lowercase, as in the following example: type=flo o Separate elements from each other with a separator (blank space, tab, or carriage return/line feed), as in the following example: record=4000 key=24 o Specify the description file elements in the proper order. Table A-1 presents the elements in the appropriate order. NOTE: The order of the elements required for the CREATE, INDEX, and SINDEX commands is the same. However, these commands do not all require the same elements. o Address all element dependencies. For example, consider the following Null Key element: null=y If you specify this element in the description file, you must also include the Null Key Value element. o Define as many keys as you specify with the Key Count element. The following example specifies 12 keys for the file: key=12 In this case, you must define 12 keys in the description file, each consisting of one or more segments. o For a key with multiple segments, you must define the following elements for each key segment: - Key Position - Key Length - Duplicate Key Values - Modifiable Key Values - Key Type - Alternate Collating Sequence The Descending Sort Order element is optional for each segment. o If any key in the file uses an alternate collating sequence, include either an alternate collating sequence filename or a country ID and code page ID. You can include this information as either the last element of the key segment or the last element in the description file. o If a description file element is optional, you can omit it from the description file. o Make sure the description file contains no text formatting characters. Some word processors embed formatting characters in a text file. Description File Example The sample description file shown in Figures A-1, A-2, and A-3 creates a Btrieve file. This Btrieve file has a page size of 512 bytes and 2 keys. The fixed-length portion of the record is 98 bytes long. The file allows variable-length records but does not use blank truncation. The file uses data compression, allows for Variable-tail Allocation Tables (VATs), and has the free space threshold set to 20 percent. Btrieve preallocates 100 pages, or 51,200 bytes, when it creates the file. The file has two keys: Key 0 and Key 1. Key 0 is a segmented key with two segments. Figure A-1 Sample Description File Using Alternate Collating Sequence Filename --------------------------------------------------------------------------- record=98 variable=y truncate=n compress=y ---+ key=2 page=512 allocation=100 replace=n | File Specifications fthreshold=20 huge=y ---+ position=1 length=5 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 1 null=y value=20 segment=y ---+ position=6 length=10 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 2 null=y value=20 segment=n ---+ position=16 length=2 duplicates=n ---+ Key 1 modifiable=y type=numeric descending=y | alternate null=n segment=n ---+ name=path/upper.alt -------------------------------------------------------------------------- In Figure A-1, an alternate collating sequence filename (UPPER.ALT) is specified for Key 0. If you specify y for the Alternate Collating Sequence element for a key, you must supply an alternate collating sequence filename or a country ID and code page ID. Figure A-2 Sample Description File Using Alternate Collating Sequence ID --------------------------------------------------------------------------- record=98 variable=y truncate=n compress=y ---+ key=2 page=512 allocation=100 replace=n | File Specifications fthreshold=20 huge=y ---+ position=1 length=5 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 1 null=y value=20 segment=y ---+ position=6 length=10 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 2 null=y value=20 segment=n ---+ position=16 length=2 duplicates=n ---+ Key 1 modifiable=y type=numeric descending=y | alternate null=n segment=n ---+ countryid=-1 codepageid=-1 -------------------------------------------------------------------------- In Figure A-2, a country ID and code page ID are specified (countryid=-1 and codepageid=-1). If you specify the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) at the end of the description file, Btrieve uses it as the default alternate collating sequence. That is, if you specify alternate=y for a given key but do not include a name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) for that key, Btrieve uses the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) specified at the end of the description file. Figure A-3 Sample Description File Using Alternate Collating Sequence Filename on a File Segment --------------------------------------------------------------------------- record=98 variable=y truncate=n compress=y ---+ key=2 page=512 allocation=100 replace=n | File Specifications fthreshold=20 huge=y ---+ position=1 length=5 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 1 null=y value=20 segment=y name=path/lower.alt ---+ position=6 length=10 duplicates=y ---+ Key 0 modifiable=n type=string alternate=y | Segment 2 null=y value=20 segment=n name=path/lower.alt ---+ position=16 length=2 duplicates=n ---+ Key 1 modifiable=y type=numeric descending=y | alternate null=n segment=n | name=path/upper.alt ---+ -------------------------------------------------------------------------- In Figure A-3, a different alternate collating sequence filename is specified for Key 0 and Key 1. If you want to use different alternate collating sequences for different keys, you must specify the name=sequenceFile element (or the countryid=nnn and codepageid=nnn elements) for each key that uses a different alternate collating sequence. Different segments of the same key cannot have different alternate collating sequences. You can specify only one alternate collating sequence per key, and you must provide an alternate collating sequence filename (or values for the countryid=nnn and codepageid=nnn elements) for each segment of the key. The filename for the name=sequenceFile element (or values for the countryid=nnn and codepageid=nnn elements) must be the same for each segment. In Figure A-3, the filename specified for each segment in Key 0 is LOWER.ALT. The filename specified for Key 1 is UPPER.ALT. Description File Elements Table A-1 lists the description file elements in the order in which they must appear in the description file. For each element, Table A-1 specifies the required format, the range of acceptable values, and the associated commands. An asterisk (*) after the element name indicates that the element is optional. Descriptions of the individual elements follow the table. Table A-1 Summary of Description File Elements -------------------------------------------------------------------------- Element Format Range Command Record Length record=nnnn 4-4,088 CREATE Variable-Length Records variable= N/A CREATE Reserved Duplicate Pointer* dupkey= 1-119 CREATE Blank Truncation* truncate= N/A CREATE Data Compression* compress= N/A CREATE Key Count key=nnn 0-118 CREATE Page Size page=nnnn 512-4,096 CREATE Page Preallocation* allocation=nnnnn 1-65,535 CREATE Replace Existing File* replace= N/A CREATE Include Data* data= N/A CREATE Free Space Threshold* fthreshold=<10|20|30> N/A CREATE Variable-Tail Allocation Tables (VATs) huge= N/A CREATE Balanced Index* balance= N/A CREATE Key Position position=nnnn 1-4,088 CREATE, INDEX, SINDEX Key Length length=nnn key type limit CREATE, INDEX, SINDEX Duplicate Key Values duplicates= N/A CREATE, INDEX, SINDEX Modifiable Key Values modifiable= N/A CREATE, INDEX, SINDEX Key Type type=validBtrieveKeyType N/A CREATE, INDEX, SINDEX Descending Sort Order* descending= N/A CREATE, INDEX, SINDEX Alternate Collating Sequence* alternate= N/A CREATE, INDEX, SINDEX Case-Insensitive Key* caseinsensitive= N/A CREATE, INDEX, SINDEX Repeating Duplicates* repeatdup= N/A CREATE, SINDEX Manual Key* manual= N/A CREATE, INDEX, SINDEX Null Key null= N/A CREATE, INDEX, SINDEX Null Key Value value=nn 1-byte hex CREATE, INDEX, SINDEX Segmented Key segment= N/A CREATE, INDEX, SINDEX Alternate Collating Sequence Filename CREATE, INDEX, SINDEX /ID name=sequenceFile or countryid=nnn and codepageid=nnn valid path or values valid to operating system or -1 (default) -------------------------------------------------------------------------- Record Length Format: record=nnnn Range: 4 through 4,088 bytes Command: CREATE The Record Length element defines the logical data record length in bytes. For fixed-length records, this value should correspond to the length of the data buffer parameter that performs operations on the file. For variable-length records, this value should correspond to the fixed-length portion of the record. The data record length must be at least 4 bytes and must be large enough to contain all the keys defined for the file. The record length (including its duplicate key overhead and usage count overhead) plus 6 bytes must not exceed the file's page size. Variable-Length Records Format: variable= Range: Not applicable Command: CREATE The Variable-Length Records element specifies whether the file will contain variable-length records. If a record is variable length, the maximum fixed-length record is decreased by 4 bytes. Specify y if you want the file to allow variable-length records; otherwise, specify n. Reserved Duplicate Pointer Format: dupkey=nnn Range: 1 through 119 Command: CREATE The Reserved Duplicate Pointer element is optional. It specifies the number of duplicate key pointers to preallocate for the file when it is created. Each reserved duplicate pointer adds 8 bytes of extra storage space to the fixed record length. These reserved pointers can be used when keys that allow duplicates are added after the file is created and if you do not specify y for the Repeating Duplicates element. Blank Truncation Format: truncate= Range: Not applicable Command: CREATE The Blank Truncation element is optional. It specifies whether Btrieve performs blank truncation on variable-length records. The truncate element has an effect only if you specify y for the Variable-Length Records element. Specify y if you want Btrieve to use blank truncation. Otherwise, either specify n or omit this element from your description file. Data Compression Format: compress= Range: Not applicable Command: CREATE The Data Compression element is optional. It specifies whether Btrieve performs data compression on records that are inserted into the file. Specify y if you want Btrieve to perform data compression. Otherwise, either specify n or omit this element from your description file. Key Count Format: key=nnn Range: 0 through 118 (see Table A-2) Command: CREATE The Key Count element specifies the number of keys to be defined in the file. If you specify a value of 0 for this element, Btrieve creates a data-only file. If you specify a value greater than 0, Btrieve creates either a standard file or a key-only file, depending on the value you specify for the Include Data element. The fileÕs page size limits the amount of key segments a file can have. Table A-2 shows the maximum key count values for each possible page size. This value represents the number of key segments, not the number of keys. There may actually be more segment definitions than the key count. For example, assume a file contains three keys: key 0 has 2 segments, key 1 has 4 segments, and key 2 has 2 segments. In this example, the file has a page size of 512, the value specified for the Key Count element is 3, and the maximum number of key segments is 8. Table A-2 Key Segment Count Values Page Size (in bytes) Maximum Number of Key Segments 512 8 1,024 23 1,536 24 2,048-3,584 54 4,096 119 Page Size Format: page=nnnn Range: 512 through 4,096 bytes Command: CREATE The Page Size element specifies the physical page size (in bytes) for the file. You can specify any multiple of 512, up to 4,096. SUGGESTION: For optimum performance, set the page size to 512, 1,024, 2,048, or 4,096 bytes. Page Preallocation Format: allocation=nnnnn Range: 1 through 65,535 Command: CREATE The Page Preallocation element is optional. It specifies the number of pages to preallocate to the file. If you do not want to preallocate any pages, either specify n or omit this element from your description file. Replace Existing File Format: replace= Range: Not applicable Command: CREATE The Replace Existing File element is optional. If you do not want to create a new, empty file over an existing Btrieve file of the same name, specify n. If you want to replace an existing Btrieve file with a new, empty file of the same name, either specify y or omit this element from your description file. Include Data Format: data= Range: Not applicable Command: CREATE The Include Data element is optional. It specifies the file type that the utility creates. To create a key-only file, specify n. To create a standard file, either specify y or omit the element from the description file. To create a data-only file, specify y and set the Key Count element to 0. Free Space Threshold Format: fthreshold=<10|20|30> Range: Not applicable Command: CREATE Btrieve stores the variable-length portions of records on their own pages (called variable pages), separate from the fixed-length portion of the record (which is stored on a data page). Btrieve maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification. You can specify a value for the Free Space Threshold element when you create the file. This value is expressed as a percentage and tells Btrieve how much free space must remain on a variable page in order for that page to appear on the Free Space List. When Btrieve adds new variable-length records to the file, it uses pages in the Free Space List before using new variable pages. After each Insert, Update, or Delete operation, Btrieve rechecks the remaining space on the affected variable page to see if it is still above the threshold to qualify for the Free Space List. The free space threshold feature provides a means of reducing the fragmentation of variable-length records across several pages. A higher free space threshold reduces fragmentation at the cost of requiring more disk space for the file. You can specify any two-digit number for this element, and the utility rounds it to 10, 20, or 30. Btrieve uses a default free space threshold of 5 percent if either of the following is true: o You specify a value less than 10. o You do not specify a value here but have specified y for the Variable-Length Records element. NOTE: If the Btrieve file does not allow variable-length records, do not include this element in the description file. Variable-Tail Allocation Tables (VATs) Format: huge= Range: Not applicable Command: CREATE The Variable-tail Allocation Tables (VATs) element is optional. Btrieve v6.1 allows an application to create Btrieve files that contain structures called Variable-tail Allocation Tables (VATs), which are implemented as linked lists. To accelerate random access to portions of records, Btrieve uses VATs with each record. VATs are also helpful in files using data compression to limit the size of the compression buffer used by Btrieve. If you want to create a file that uses VATs, specify y. Otherwise, either specify n or omit this element from your description file. For more information about VATs, refer to the Btrieve Programmer's Manual. Balanced Index Format: balance= Range: Not applicable Commands: CREATE The Balanced Index element is optional. This feature allows you to use index balancing. With index balancing, Btrieve looks for available space in sibling index pages each time an index page becomes full and then rotates values from the full page into the pages with space available. Index balancing increases index page utilization, results in fewer pages, and produces an even distribution of keys among nodes on the same level, thus enhancing performance during Get operations. However, the use of this feature also means that Btrieve requires extra time to examine more index pages and may require more disk I/O during Insert, Update, and Delete operations. NOTE: You can specify index balancing on a file-by-file basis when the file is created. When you specify index balancing for a specific file, Btrieve will always balance that file's keys. You can also turn index balancing on and off for files that are not flagged as balanced by specifying Yes to the Perform Index Balancing configuration option in the Setup utility. To use index balancing, specify y. Otherwise, either specify n or omit this element from the description file. Key Position Format: position=nnnn Range: 1 through value specified for Record Length element (up to 4,088) Commands: CREATE, INDEX, SINDEX The Key Position element indicates the position of the key segment in the record. The key position value must be at least 1 and cannot exceed the value you specified for the Record Length element. Key Length Format: length=nnn Range: 1 through limit determined by key type Commands: CREATE, INDEX, SINDEX The Key Length element defines the length of the key or key segment field. The value you specify here cannot exceed the limit dictated by the key type, which the Key Type element specifies. The key length must be an even number if the key is a binary key type. The total of the key's length and starting position cannot exceed the file's defined record length. Duplicate Key Values Format: duplicates= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Duplicate Key Values element specifies whether more than one record in the file can contain the same value for this key field. Specify y if you want to allow duplicate values for the key field; otherwise, specify n. NOTE: If you define duplicate key values for one segment of a segmented key, you must define duplicate key values for every segment of that key. For a segmented key that does not allow duplicates, the segments may contain duplicates between multiple records only if the key value is unique for each record. Modifiable Key Values Format: modifiable= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Modifiable Key Values element specifies whether the key value can be modified during an Update operation. Specify y if you want the values for this key to be modifiable; otherwise, specify n. NOTE: If you define modifiable key values for one segment of a segmented key, you must define modifiable key values for every segment of that key because the key, as a whole, is modifiable. Key Type Format: type=validBtrieveKeyType Range: Not applicable Commands: CREATE, INDEX, SINDEX The Key Type element specifies the Btrieve data type for the key. This element determines how Btrieve will sort the bytes specified for this key segment. Btrieve does not perform any validation on the data inserted. You can specify the entire word (as in float) or just the first three letters of the word (as in flo for float). The Btrieve key types are as follows: autoinc integer string bfloat logicaltimedatelstringunsigned binary decimalmoneyzstring floatnumericsign trailing separate NOTE: STS (sign trailing separate) is a COBOL data type. It is basically a numeric data type, represented as an ASCII string. STS is right justified and padded with leading ASCII zeros, and it has the sign byte at the end. Descending Sort Order Format: descending= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Descending Sort Order element is optional. It specifies whether Btrieve will collate the index or index segment in descending order. Specify y if you want Btrieve to collate the key values in descending order. If you want Btrieve to collate the index in ascending order, either specify n or omit this element from the description file. Alternate Collating Sequence Format: alternate= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Alternate Collating Sequence element is optional. This element allows you to specify one or more alternate collating sequences for a given file. An alternate collating sequence specifies whether Btrieve will sort a key by a collating sequence other than the standard ASCII sequence. You can specify a different alternate collating sequence for each key. However, each segment of the key can have only one alternate collating sequence. Alternate collating sequences are valid only for string, lstring, and zstring key types. If you want the key to take advantage of an alternate collating sequence, specify y. Otherwise, either specify n or omit this element from the description file. When using a description file to create an additional index for an existing Btrieve file, if you want the index to use an alternate collating sequence file other than the first one in the Btrieve file, specify alternate=y and caseinsensitive=y. If you specify alternate=y and caseinsensitive=n and use an alternate collating sequence file other than the first one in the Btrieve file, the index will not be created. Case-Insensitive Key Format: caseinsensitive= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Case-Insensitive Key element is optional. It specifies that the key (or key segment) you are defining is case insensitive. You can specify this key element only for keys that are of type string, zstring, or lstring. By default, Btrieve is case sensitive when sorting key strings; that is, it sorts string key values based on whether the letters are uppercase or lowercase. Btrieve sorts the values by placing the uppercase value first, followed by the lowercase value. For example, key values starting with A would appear before those starting with a in the index. Case sensitivity, however, does not apply if Btrieve sorts a key according to the collating sequence specified with the Alternate Collating Sequence element. To specify that Btrieve ignore case when sorting the key value, specify y for this element. Otherwise, either specify n or omit this element from the description file. Repeating Duplicates Format: repeatdup= Range: Not applicable Commands: CREATE, INDEX, SINDEX Btrieve uses two methods for storing duplicatable keys internally. The keys are stored as either linked-duplicatable keys or repeating-duplicatable keys. o Linked-duplicatable key-In a Btrieve v6.1 file, Btrieve stores duplicatable keys as linked-duplicatable keys by default on a Create operation. (On a Create Index operation, Btrieve uses linked-duplicatable keys if they are available; otherwise, it uses repeating-duplicatable keys, as explained in the following section.) Using this method, Btrieve stores the key extracted from the first record of a duplicatable key on an index page. Other records with keys containing duplicate values are stored in the form of a linked list, with pointers at the end of each record in a data page pointing to the next and the previous records that have the same duplicate key values. o Repeating-duplicatable key-If no room is available to create a linked-duplicatable key (that is, if no duplicate pointers were reserved at file creation, or if no index has been dropped to free existing pointers), Btrieve stores duplicatable keys as repeating-duplicatable keys. Using this method, Btrieve stores every key value of a repeating-duplicatable key both in a data page and in an index page. NOTE: Key-only files always use repeating-duplicatable keys because the key-only files use only the index pages and not the data pages. Specify y to create repeating-duplicatable keys. Otherwise, either specify n or omit this element from the description file. NOTE: For a segmented key, all segments must have the same repeatdup=y/n specification. For a nonsegmented key, if you specify repeatdup=y, you must also specify duplicate=y. Manual Key Format: manual= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Manual Key element is optional. It specifies that the key or key segment you are defining is manual. A manual key is a modified form of the null key and can be used to exclude particular records from the index. Manual keys have all the attributes of a null key with one exception: in a manual key, if every byte of one segment of the key contains the null value, Btrieve excludes the key from the index even if other segments do not contain this null value. If you define one segment of a key as a manual a null value for that segment, and you must define all other segments of that key as manual. However, Btrieve allows you to define different null values for different segments in a segmented key. To create a manual key or key segment, specify y; otherwise, specify n or omit this element from your description file. NOTE: The Btrieve Programmer's Manual refers to manual keys as "any-segment null keys." Null Key Format: null= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Null Key element specifies whether the key you are defining has a null value. You can include the Null Key element in a description file for the INDEX command. However, to maintain consistent formats for the CREATE, INDEX, and SINDEX description files, INDEX disregards any null value you specify. If you define a null value for one segment of a segmented key, you must define a null value for every segment of that key. However, Btrieve allows you to define different null values for different segments in a segmented key. Specify y if you want to define a null value for this key. Otherwise, specify n. NOTE: The Btrieve Programmer's Manual refers to null keys as "all-segment null keys." Null Key Value Format: value=nn Range: Any 1-byte hexadecimal value Commands: CREATE, INDEX, SINDEX The Null Key Value element specifies the null character value (in hexadecimal) for the key. Typical null values are 20 hexadecimal (blank) and 0 hexadecimal (binary zero). Include this element only if you defined the key as allowing null values. If you specify n for both the Null Key element and the Manual Key element, the Null Key Value element is not required in the description file. Segmented Key Format: segment= Range: Not applicable Commands: CREATE, INDEX, SINDEX The Segmented Key element specifies whether the key you are defining has any more segments. Specify y if the key has another segment. Specify n if you are defining either a nonsegmented key or the last segment of a segmented key. Alternate Collating Sequence Filename/ID Format: name=sequenceFile or countryid=nnn codepageid=nnn Range: Any valid, fully qualified pathname; or a valid country ID and code page ID; or -1 (the default) Commands: CREATE, INDEX, SINDEX The Alternate Collating Sequence Filename/ID element specifies the pathname of the file that contains an alternate collating sequence for the file you are creating. You can include up to 256 bytes of directory levels in the pathname (plus the filename). If you specified n for the Alternate Collating Sequence element for every key, do not include this element in your description file. If you specified y for the Alternate Collating Sequence element for a key, you must supply either an alternate collating sequence filename or a country ID and a code page ID. If you want all the keys in the file to use the same alternate collating sequence filename, you can either specify this element as the last element in the description file or specify the alternate collating sequence name for each key. If you want to use different alternate collating sequences, you must specify this element for each key that uses an alternate collating sequence. You can specify only one alternate collating sequence per key, and each segment of the key should have an alternate= and name= pair. To use an alternate collating sequence ID, you must specify countryid=nnn and codepageid=nnn. Use a valid country ID and code page ID. If you want to use the current locale, specify countryid=-1 and codepageid= -1. The first 265 bytes of an alternating collating sequence file contain the definition of a collating sequence other than the standard ASCII sequence. If you want to create an alternate collating sequence file, generate a file in the format that Table A-3 specifies. Table A-3 Alternate Collating Sequence File Format Offset Length Description 0 1 Signature byte. This byte should always contain the value ACh. 1 8 An 8-byte name that uniquely identifies the alternate collating sequence to Btrieve. 9 256 A 256-byte table containing the sort value for every character. Store the value for each sort character at the offset corresponding to the character's representation in the ASCII collating sequence. For example, to sort the character A as something other than 41h, store the new sort value at offset 41h in the table. For example, assume you want to insert a character with a 5Dh between the letters U (55h) and V (56h) in your sequence. In this case, byte 5Dh in the sequence should contain the value 56h, and bytes 56h through 5Ch in the sequence should contain the values 57h through 5Dh.